Developer CD Series 1998 April: Mac OS SDK

home *** CD-ROM | disk | FTP | other *** search

/ Developer CD Series 1998 April: Mac OS SDK / Dev.CD Apr 98 SDK1.toast / Development Kits (Disc 1) / Interfaces&Libraries / Universal / Interfaces / AIncludes / QD3DRenderer.a < prev next >

Wrap

Text File | 1998-02-12 | 40.7 KB | 1,276 lines | [TEXT/MPS ]

; ; File: QD3DRenderer.a ; ; Contains: Q3Renderer types and routines ; ; Version: Technology: Quickdraw 3D 1.5.4 ; Release: Universal Interfaces 3.1 ; ; Copyright: © 1995-1998 by Apple Computer, Inc., all rights reserved. ; ; Bugs?: Please include the the file and version information (from above) with ; the problem description. Developers belonging to one of the Apple ; developer programs can submit bug reports to: ; ; devsupport@apple.com ; ; IF &TYPE('__QD3DRENDERER__') = 'UNDEFINED' THEN __QD3DRENDERER__ SET 1 IF &TYPE('__QD3D__') = 'UNDEFINED' THEN include 'QD3D.a' ENDIF IF &TYPE('__QD3DSET__') = 'UNDEFINED' THEN include 'QD3DSet.a' ENDIF IF &TYPE('__QD3DVIEW__') = 'UNDEFINED' THEN include 'QD3DView.a' ENDIF IF TARGET_OS_MAC THEN IF &TYPE('__EVENTS__') = 'UNDEFINED' THEN include 'Events.a' ENDIF ENDIF ; TARGET_OS_MAC ; ****************************************************************************** ; ** ** ; ** User Interface Things ** ; ** ** ; **************************************************************************** IF TARGET_OS_MAC THEN ; ; * A callback to an application's event handling code. This is needed to ; * support movable modal dialogs. The dialog's event filter calls this ; * callback with events it does not handle. ; * If an application handles the event it should return kQ3True. ; * If the application does not handle the event it must return kQ3False and ; * the dialog's event filter will pass the event to the system unhandled. ; TQ3DialogAnchor RECORD 0 clientEventHandler ds.l 1 ; offset: $0 (0) sizeof EQU * ; size: $4 (4) ENDR ENDIF ; TARGET_OS_MAC IF TARGET_OS_WIN32 THEN TQ3DialogAnchor RECORD 0 ownerWindow ds.l 1 ; offset: $0 (0) sizeof EQU * ; size: $4 (4) ENDR ENDIF ; TARGET_OS_WIN32 IF TARGET_OS_UNIX THEN TQ3DialogAnchor RECORD 0 notUsed ds.l 1 ; offset: $0 (0) ; place holder sizeof EQU * ; size: $4 (4) ENDR ENDIF ; TARGET_OS_UNIX ; ****************************************************************************** ; ** ** ; ** Renderer Functions ** ; ** ** ; **************************************************************************** ; ; extern TQ3RendererObject Q3Renderer_NewFromType(TQ3ObjectType rendererObjectType) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION Q3Renderer_NewFromType ENDIF ; ; extern TQ3ObjectType Q3Renderer_GetType(TQ3RendererObject renderer) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION Q3Renderer_GetType ENDIF ; Q3Renderer_Flush has been replaced by Q3View_Flush ; Q3Renderer_Sync has been replaced by Q3View_Sync ; ; * Q3Renderer_IsInteractive ; * Determine if this renderer is intended to be used interactively. ; ; ; extern TQ3Boolean Q3Renderer_IsInteractive(TQ3RendererObject renderer) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION Q3Renderer_IsInteractive ENDIF ; ; * Q3Renderer_HasModalConfigure ; * Determine if this renderer has a modal settings dialog. ; * ; * Q3Renderer_ModalConfigure ; * Have the renderer pop up a modal dialog box to configure its settings. ; * dialogAnchor - is platform specific data passed by the client to support ; * movable modal dialogs. ; * MacOS: this is a callback to the calling application's event handler. ; * The renderer calls this function with events not handled by the ; * settings dialog. This is necessary in order to support movable modal ; * dialogs. An application's event handler must return kQ3True if it ; * handles the event passed to the callback or kQ3False if not. ; * An application which doesn't want to support a movable modal configure ; * dialog should pass NULL for the clientEventHandler of TQ3DialogAnchor. ; * Win32: this is the HWND of the owning window (typically an application's ; * main window). ; * canceled - returns a boolean inditacating that the user canceled the ; * dialog. ; * ; ; ; extern TQ3Boolean Q3Renderer_HasModalConfigure(TQ3RendererObject renderer) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION Q3Renderer_HasModalConfigure ENDIF ; ; extern TQ3Status Q3Renderer_ModalConfigure(TQ3RendererObject renderer, TQ3DialogAnchor dialogAnchor, TQ3Boolean *canceled) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION Q3Renderer_ModalConfigure ENDIF ; ; * Q3RendererClass_GetNickNameString ; * Allows an application to get a renderers name string, the ; * renderer is responsible for storing this in a localizable format ; * for example as a resource. This string can then be used to provide ; * a selection mechanism for an application (for example in a menu). ; * ; * If this call returns nil in the supplied string, then the App may ; * choose to use the class name for the renderer. You should always ; * try to get the name string before using the class name, since the ; * class name is not localizable. ; ; ; extern TQ3Status Q3RendererClass_GetNickNameString(TQ3ObjectType rendererClassType, TQ3ObjectClassNameString rendererClassString) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION Q3RendererClass_GetNickNameString ENDIF ; ; * Q3Renderer_GetConfigurationData ; * Allows an application to collect private renderer configuration data ; * which it will then save. For example in a preference file or in a ; * style template. An application should tag this data with the ; * Renderer's object name. ; * ; * if dataBuffer is NULL actualDataSize returns the required size in ; * bytes of a data buffer large enough to store private data. ; * ; * bufferSize is the actual size of the memory block pointed to by ; * dataBuffer ; * ; * actualDataSize - on return the actual number of bytes written to the ; * buffer or if dataBuffer is NULL the required size of dataBuffer ; * ; ; ; extern TQ3Status Q3Renderer_GetConfigurationData(TQ3RendererObject renderer, unsigned char *dataBuffer, unsigned long bufferSize, unsigned long *actualDataSize) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION Q3Renderer_GetConfigurationData ENDIF ; ; extern TQ3Status Q3Renderer_SetConfigurationData(TQ3RendererObject renderer, unsigned char *dataBuffer, unsigned long bufferSize) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION Q3Renderer_SetConfigurationData ENDIF ; ****************************************************************************** ; ** ** ; ** Interactive Renderer Specific Functions ** ; ** ** ; **************************************************************************** ; CSG IDs attribute ; Object IDs, to be applied as attributes on geometries kQ3AttributeTypeConstructiveSolidGeometryID EQU 'csgi' kQ3SolidGeometryObjNone EQU -1 kQ3SolidGeometryObjA EQU 0 kQ3SolidGeometryObjB EQU 1 kQ3SolidGeometryObjC EQU 2 kQ3SolidGeometryObjD EQU 3 kQ3SolidGeometryObjE EQU 4 ; Possible CSG equations ; typedef long TQ3CSGEquation kQ3CSGEquationAandB EQU $88888888 kQ3CSGEquationAandnotB EQU $22222222 kQ3CSGEquationAanBonCad EQU $2F222F22 kQ3CSGEquationnotAandB EQU $44444444 kQ3CSGEquationnAaBorCanB EQU $74747474 ; typedef long TQ3HiddenSurfaceRemovalMode kQ3HiddenSurfaceRemovalMode_None EQU 0 kQ3HiddenSurfaceRemovalMode_Shallow EQU 1 kQ3HiddenSurfaceRemovalMode_Deep EQU 2 ; ; extern TQ3Status Q3InteractiveRenderer_SetCSGEquation(TQ3RendererObject renderer, TQ3CSGEquation equation) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION Q3InteractiveRenderer_SetCSGEquation ENDIF ; ; extern TQ3Status Q3InteractiveRenderer_GetCSGEquation(TQ3RendererObject renderer, TQ3CSGEquation *equation) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION Q3InteractiveRenderer_GetCSGEquation ENDIF ; ; extern TQ3Status Q3InteractiveRenderer_SetPreferences(TQ3RendererObject renderer, long vendorID, long engineID) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION Q3InteractiveRenderer_SetPreferences ENDIF ; ; extern TQ3Status Q3InteractiveRenderer_GetPreferences(TQ3RendererObject renderer, long *vendorID, long *engineID) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION Q3InteractiveRenderer_GetPreferences ENDIF ; ; extern TQ3Status Q3InteractiveRenderer_SetDoubleBufferBypass(TQ3RendererObject renderer, TQ3Boolean bypass) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION Q3InteractiveRenderer_SetDoubleBufferBypass ENDIF ; ; extern TQ3Status Q3InteractiveRenderer_GetDoubleBufferBypass(TQ3RendererObject renderer, TQ3Boolean *bypass) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION Q3InteractiveRenderer_GetDoubleBufferBypass ENDIF ; ; extern TQ3Status Q3InteractiveRenderer_SetRAVEContextHints(TQ3RendererObject renderer, unsigned long RAVEContextHints) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION Q3InteractiveRenderer_SetRAVEContextHints ENDIF ; ; extern TQ3Status Q3InteractiveRenderer_GetRAVEContextHints(TQ3RendererObject renderer, unsigned long *RAVEContextHints) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION Q3InteractiveRenderer_GetRAVEContextHints ENDIF ; ; extern TQ3Status Q3InteractiveRenderer_SetRAVETextureFilter(TQ3RendererObject renderer, unsigned long RAVEtextureFilterValue) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION Q3InteractiveRenderer_SetRAVETextureFilter ENDIF ; ; extern TQ3Status Q3InteractiveRenderer_GetRAVETextureFilter(TQ3RendererObject renderer, unsigned long *RAVEtextureFilterValue) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION Q3InteractiveRenderer_GetRAVETextureFilter ENDIF ; ****************************************************************************** ; ** ** ; ** Renderer View Tools ** ; ** ** ; ** You may only call these methods from a plug-in ** ; ** ** ; **************************************************************************** ; ; * Call by a renderer to call the user "idle" method, with progress ; * information. ; * ; * Pass in (view, 0, n) on first call ; * Pass in (view, 1..n-1, n) during rendering ; * Pass in (view, n, n) upon completion ; * ; * Note: The user must have supplied an idleProgress method with ; * Q3XView_SetIdleProgressMethod. Otherwise, the generic idle method is ; * called with no progress data. e.g. the Q3View_SetIdleMethod method ; * is called instead. (current and final are ignored, essentially.) ; * ; * Returns kQ3Failure if rendering is cancelled. ; ; ; extern TQ3Status Q3XView_IdleProgress(TQ3ViewObject view, unsigned long current, unsigned long completed) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION Q3XView_IdleProgress ENDIF ; ; * Called by an asynchronous renderer when it completes a frame. ; ; ; extern TQ3Status Q3XView_EndFrame(TQ3ViewObject view) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION Q3XView_EndFrame ENDIF ; ****************************************************************************** ; ** ** ; ** Renderer AttributeSet Tools ** ; ** ** ; ** You may only call these methods from a plug-in ** ; ** ** ; **************************************************************************** ; ; * Faster access to geometry attribute sets. ; * ; * Returns pointer to INTERNAL data structure for elements and attributes ; * in an attributeSet, or NULL if no attribute exists. ; * ; * For attributes of type kQ3AttributeType..., the internal data structure ; * is identical to the data structure used in Q3AttributeSet_Add. ; ; ; extern void *Q3XAttributeSet_GetPointer(TQ3AttributeSet attributeSet, TQ3AttributeType attributeType) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION Q3XAttributeSet_GetPointer ENDIF kQ3XAttributeMaskNone EQU 0 kQ3XAttributeMaskSurfaceUV EQU $01 kQ3XAttributeMaskShadingUV EQU $02 kQ3XAttributeMaskNormal EQU $04 kQ3XAttributeMaskAmbientCoefficient EQU $08 kQ3XAttributeMaskDiffuseColor EQU $10 kQ3XAttributeMaskSpecularColor EQU $20 kQ3XAttributeMaskSpecularControl EQU $40 kQ3XAttributeMaskTransparencyColor EQU $80 kQ3XAttributeMaskSurfaceTangent EQU $0100 kQ3XAttributeMaskHighlightState EQU $0200 kQ3XAttributeMaskSurfaceShader EQU $0400 kQ3XAttributeMaskCustomAttribute EQU $80000000 kQ3XAttributeMaskAll EQU $800007FF kQ3XAttributeMaskInherited EQU $03FF kQ3XAttributeMaskInterpolated EQU $01FF ; typedef unsigned long TQ3XAttributeMask ; ; extern TQ3XAttributeMask Q3XAttributeSet_GetMask(TQ3AttributeSet attributeSet) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION Q3XAttributeSet_GetMask ENDIF ; ****************************************************************************** ; ** ** ; ** Renderer Draw Context Tools ** ; ** ** ; **************************************************************************** ; ; extern TQ3Status Q3XDrawContext_GetDrawRegion(TQ3DrawContextObject drawContext, TQ3XDrawRegion *drawRegion) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION Q3XDrawContext_GetDrawRegion ENDIF ; typedef long TQ3XDrawContextValidationMasks kQ3XDrawContextValidationClearFlags EQU $00000000 kQ3XDrawContextValidationDoubleBuffer EQU $01 kQ3XDrawContextValidationShader EQU $02 kQ3XDrawContextValidationClearFunction EQU $04 kQ3XDrawContextValidationActiveBuffer EQU $08 kQ3XDrawContextValidationInternalOffScreen EQU $10 kQ3XDrawContextValidationPane EQU $20 kQ3XDrawContextValidationMask EQU $40 kQ3XDrawContextValidationDevice EQU $80 kQ3XDrawContextValidationWindow EQU $0100 kQ3XDrawContextValidationWindowSize EQU $0200 kQ3XDrawContextValidationWindowClip EQU $0400 kQ3XDrawContextValidationWindowPosition EQU $0800 kQ3XDrawContextValidationPlatformAttributes EQU $1000 kQ3XDrawContextValidationForegroundShader EQU $2000 kQ3XDrawContextValidationBackgroundShader EQU $4000 kQ3XDrawContextValidationColorPalette EQU $8000 kQ3XDrawContextValidationAll EQU $FFFFFFFF ; typedef unsigned long TQ3XDrawContextValidation ; ; extern TQ3Status Q3XDrawContext_ClearValidationFlags(TQ3DrawContextObject drawContext) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION Q3XDrawContext_ClearValidationFlags ENDIF ; ; extern TQ3Status Q3XDrawContext_GetValidationFlags(TQ3DrawContextObject drawContext, TQ3XDrawContextValidation *validationFlags) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION Q3XDrawContext_GetValidationFlags ENDIF ; ****************************************************************************** ; ** ** ; ** Renderer Draw Region Tools ** ; ** ** ; **************************************************************************** ; typedef long TQ3XDevicePixelType ; These do not indicate byte ordering kQ3XDevicePixelTypeInvalid EQU 0 ; Unknown, un-initialized type kQ3XDevicePixelTypeRGB32 EQU 1 ; Alpha:8 (ignored), R:8, G:8, B:8 kQ3XDevicePixelTypeARGB32 EQU 2 ; Alpha:8, R:8, G:8, B:8 kQ3XDevicePixelTypeRGB24 EQU 3 ; 24 bits/pixel, R:8, G:8, B:8 kQ3XDevicePixelTypeRGB16 EQU 4 ; Alpha:1 (ignored), R:5, G:5, B:5 kQ3XDevicePixelTypeARGB16 EQU 5 ; Alpha:1, R:5, G:5, B:5 kQ3XDevicePixelTypeRGB16_565 EQU 6 ; 16 bits/pixel, R:5, G:6, B:5 kQ3XDevicePixelTypeIndexed8 EQU 7 ; 8-bit color table index kQ3XDevicePixelTypeIndexed4 EQU 8 ; 4-bit color table index kQ3XDevicePixelTypeIndexed2 EQU 9 ; 2-bit color table index kQ3XDevicePixelTypeIndexed1 EQU 10 ; 1-bit color table index ; typedef long TQ3XClipMaskState kQ3XClipMaskFullyExposed EQU 0 kQ3XClipMaskPartiallyExposed EQU 1 kQ3XClipMaskNotExposed EQU 2 TQ3XColorDescriptor RECORD 0 redShift ds.l 1 ; offset: $0 (0) redMask ds.l 1 ; offset: $4 (4) greenShift ds.l 1 ; offset: $8 (8) greenMask ds.l 1 ; offset: $C (12) blueShift ds.l 1 ; offset: $10 (16) blueMask ds.l 1 ; offset: $14 (20) alphaShift ds.l 1 ; offset: $18 (24) alphaMask ds.l 1 ; offset: $1C (28) sizeof EQU * ; size: $20 (32) ENDR TQ3XDrawRegionDescriptor RECORD 0 width ds.l 1 ; offset: $0 (0) height ds.l 1 ; offset: $4 (4) rowBytes ds.l 1 ; offset: $8 (8) pixelSize ds.l 1 ; offset: $C (12) pixelType ds.l 1 ; offset: $10 (16) colorDescriptor ds TQ3XColorDescriptor ; offset: $14 (20) bitOrder ds.l 1 ; offset: $34 (52) byteOrder ds.l 1 ; offset: $38 (56) clipMask ds.l 1 ; offset: $3C (60) sizeof EQU * ; size: $40 (64) ENDR ; typedef long TQ3XDrawRegionServicesMasks kQ3XDrawRegionServicesNoneFlag EQU 0 kQ3XDrawRegionServicesClearFlag EQU $01 kQ3XDrawRegionServicesDontLockDDSurfaceFlag EQU $02 ; typedef unsigned long TQ3XDrawRegionServices ; ; extern TQ3Status Q3XDrawRegion_GetDeviceScaleX(TQ3XDrawRegion drawRegion, float *deviceScaleX) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION Q3XDrawRegion_GetDeviceScaleX ENDIF ; ; extern TQ3Status Q3XDrawRegion_GetDeviceScaleY(TQ3XDrawRegion drawRegion, float *deviceScaleY) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION Q3XDrawRegion_GetDeviceScaleY ENDIF ; ; extern TQ3Status Q3XDrawRegion_GetDeviceOffsetX(TQ3XDrawRegion drawRegion, float *deviceOffsetX) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION Q3XDrawRegion_GetDeviceOffsetX ENDIF ; ; extern TQ3Status Q3XDrawRegion_GetDeviceOffsetY(TQ3XDrawRegion drawRegion, float *deviceOffsetX) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION Q3XDrawRegion_GetDeviceOffsetY ENDIF ; ; extern TQ3Status Q3XDrawRegion_GetWindowScaleX(TQ3XDrawRegion drawRegion, float *windowScaleX) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION Q3XDrawRegion_GetWindowScaleX ENDIF ; ; extern TQ3Status Q3XDrawRegion_GetWindowScaleY(TQ3XDrawRegion drawRegion, float *windowScaleY) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION Q3XDrawRegion_GetWindowScaleY ENDIF ; ; extern TQ3Status Q3XDrawRegion_GetWindowOffsetX(TQ3XDrawRegion drawRegion, float *windowOffsetX) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION Q3XDrawRegion_GetWindowOffsetX ENDIF ; ; extern TQ3Status Q3XDrawRegion_GetWindowOffsetY(TQ3XDrawRegion drawRegion, float *windowOffsetY) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION Q3XDrawRegion_GetWindowOffsetY ENDIF ; ; extern TQ3Status Q3XDrawRegion_IsActive(TQ3XDrawRegion drawRegion, TQ3Boolean *isActive) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION Q3XDrawRegion_IsActive ENDIF ; ; extern TQ3Status Q3XDrawRegion_GetNextRegion(TQ3XDrawRegion drawRegion, TQ3XDrawRegion *nextDrawRegion) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION Q3XDrawRegion_GetNextRegion ENDIF ; ; * One of the next two functions must be called before using a draw region ; ; ; * Use this Start function if double buffering/image access services from the ; * Draw Context are not needed, you may still request clear for example ; ; ; extern TQ3Status Q3XDrawRegion_Start(TQ3XDrawRegion drawRegion, TQ3XDrawRegionServices services, TQ3XDrawRegionDescriptor **descriptor) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION Q3XDrawRegion_Start ENDIF ; ; * Use this Start function if double buffering or image access services from ; * the Draw Context are needed. ; ; ; extern TQ3Status Q3XDrawRegion_StartAccessToImageBuffer(TQ3XDrawRegion drawRegion, TQ3XDrawRegionServices services, TQ3XDrawRegionDescriptor **descriptor, void **image) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION Q3XDrawRegion_StartAccessToImageBuffer ENDIF ; ; * This function is used to indicate that access to a DrawRegion is ended. ; ; ; extern TQ3Status Q3XDrawRegion_End(TQ3XDrawRegion drawRegion) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION Q3XDrawRegion_End ENDIF ; ; extern TQ3Status Q3XDrawRegion_GetDeviceTransform(TQ3XDrawRegion drawRegion, TQ3Matrix4x4 **deviceTransform) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION Q3XDrawRegion_GetDeviceTransform ENDIF ; ; extern TQ3Status Q3XDrawRegion_GetClipFlags(TQ3XDrawRegion drawRegion, TQ3XClipMaskState *clipMaskState) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION Q3XDrawRegion_GetClipFlags ENDIF ; ; extern TQ3Status Q3XDrawRegion_GetClipMask(TQ3XDrawRegion drawRegion, TQ3Bitmap **clipMask) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION Q3XDrawRegion_GetClipMask ENDIF IF TARGET_OS_MAC THEN ; ; extern TQ3Status Q3XDrawRegion_GetClipRegion(TQ3XDrawRegion drawRegion, RgnHandle *rgnHandle) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION Q3XDrawRegion_GetClipRegion ENDIF ; ; extern TQ3Status Q3XDrawRegion_GetGDHandle(TQ3XDrawRegion drawRegion, GDHandle *gdHandle) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION Q3XDrawRegion_GetGDHandle ENDIF ENDIF ; TARGET_OS_MAC ; ; extern TQ3Status Q3XDrawRegion_GetRendererPrivate(TQ3XDrawRegion drawRegion, void **rendererPrivate) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION Q3XDrawRegion_GetRendererPrivate ENDIF ; ; extern TQ3Status Q3XDrawRegion_SetRendererPrivate(TQ3XDrawRegion drawRegion, const void *rendererPrivate, TQ3XDrawRegionRendererPrivateDeleteMethod deleteMethod) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION Q3XDrawRegion_SetRendererPrivate ENDIF ; ; extern TQ3Status Q3XDrawRegion_SetUseDefaultRendererFlag(TQ3XDrawRegion drawRegion, TQ3Boolean flag) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION Q3XDrawRegion_SetUseDefaultRendererFlag ENDIF ; ; extern TQ3Status Q3XDrawRegion_GetUseDefaultRendererFlag(TQ3XDrawRegion drawRegion, TQ3Boolean *useDefaultRenderingFlag) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION Q3XDrawRegion_GetUseDefaultRendererFlag ENDIF ; ****************************************************************************** ; ** ** ; ** Renderer Class Methods ** ; ** ** ; **************************************************************************** ; ; * Methods from Object ; * kQ3XMethodTypeObjectClassRegister ; * kQ3XMethodTypeObjectClassUnregister ; * kQ3XMethodTypeObjectNew ; * kQ3XMethodTypeObjectDelete ; * kQ3XMethodTypeObjectRead ; * kQ3XMethodTypeObjectTraverse ; * kQ3XMethodTypeObjectWrite ; * ; * Methods from Shared ; * kQ3MethodTypeSharedEdited ; * ; * Renderer Methods ; * ; * The renderer methods should be implemented according to the type ; * of renderer being written. ; * ; * For the purposes of documentation, there are two basic types of ; * renderers: ; * ; * Interactive ; * Interactive Renderer ; * WireFrame Renderer ; * ; * Deferred ; * a ray-tracer ; * painter's algorithm renderer (cached in a BSP triangle tree) ; * an artistic renderer (simulates a pencil drawing, etc.) ; * ; * The main difference is how each renderer handles incoming state and ; * geometry. ; * ; * An interactive renderer immediately transforms, culls, and shades ; * incoming geometry and performs rasterization. For example, in a ; * single-buffered WireFrame renderer, you will see a new triangle ; * immediately after Q3Triangle_Draw (if it's visible, of course). ; * ; * A deferred renderer caches the view state and each geometry, ; * converting into any internal queue of drawing commands. Rasterization ; * is not actually performed until all data has been submitted. ; * ; * For example, a ray-tracer may not rasterize anything until the ; * end of the rendering loop, or until an EndFrame call is made. ; ; ****************************************************************************** ; ** ** ; ** Renderer User Interface Methods ** ; ** ** ; **************************************************************************** ; ; * kQ3XMethodTypeRendererIsInteractive ; * ; * There is no actual method with this - the metahandler simply returns ; * "(TQ3XFunctionPointer)kQ3True" for this "method" if the renderer is ; * intended to be used in interactive settings, and ; * "(TQ3XFunctionPointer)kQ3False" otherwise. ; * ; * If neither value is specified in the metahandler, the renderer ; * is *assumed to be non-interactive*!!! ; * ; * OPTIONAL ; kQ3XMethodTypeRendererIsInteractive EQU 'isin' ; ; * TQ3XRendererModalConfigureMethod ; * ; * This method should pop up a modal dialog to edit the renderer settings ; * found in the renderer private. ; * ; * dialogAnchor - is platform specific data passed by the client to support ; * movable modal dialogs. ; * MacOS: this is a callback to the calling application's event handler. ; * The renderer calls this function with events not handled by the ; * settings dialog. This is necessary in order to support movable modal ; * dialogs. An application's event handler must return kQ3True if it ; * handles the event passed to the callback or kQ3False if not. ; * An application which doesn't want to support a movable modal configure ; * dialog should pass NULL for the clientEventHandler of TQ3DialogAnchor. ; * A renderer should implement a non-movable style dialog in that case. ; * Win32: this is the HWND of the owning window (typically an application's ; * main window). (Win32 application modal dialogs are always movable.) ; * canceled - returns a boolean inditacating that the user canceled the ; * dialog. ; * ; * OPTIONAL ; kQ3XMethodTypeRendererModalConfigure EQU 'rdmc' ; ; * kQ3XMethodTypeRendererGetNickNameString ; * ; * Allows an application to collect the name of the renderer for ; * display in a user interface item such as a menu. ; * ; * If dataBuffer is NULL actualDataSize returns the required size in ; * bytes of a data buffer large enough to store the renderer name. ; * ; * bufferSize is the actual size of the memory block pointed to by ; * dataBuffer ; * ; * actualDataSize - on return the actual number of bytes written to the ; * buffer or if dataBuffer is NULL the required size of dataBuffer ; * ; * OPTIONAL ; kQ3XMethodTypeRendererGetNickNameString EQU 'rdns' ; ; * kQ3XMethodTypeRendererGetConfigurationData ; * ; * Allows an application to collect private configuration data from the ; * renderer which it will then save. For example in a preference file, ; * a registry key (on Windows) or in a style template. An application ; * should tag this data with the renderer's object name. ; * ; * If dataBuffer is NULL actualDataSize returns the required size in ; * bytes of a data buffer large enough to store private data. ; * ; * bufferSize is the actual size of the memory block pointed to by ; * dataBuffer ; * ; * actualDataSize - on return the actual number of bytes written to the ; * buffer or if dataBuffer is NULL the required size of dataBuffer ; * ; * OPTIONAL ; kQ3XMethodTypeRendererGetConfigurationData EQU 'rdgp' ; ; * TQ3XRendererSetConfigurationDataMethod ; * ; * Allows an application to pass private configuration data which has ; * previously been obtained from a renderer via ; * Q3Renderer_GetConfigurationData. For example in a preference file or ; * in a style template. An application should tag this data with the ; * renderer's object name. ; * ; * bufferSize is the actual size of the memory block pointed to by ; * dataBuffer ; * ; * OPTIONAL ; kQ3XMethodTypeRendererSetConfigurationData EQU 'rdsp' ; ****************************************************************************** ; ** ** ; ** Renderer Drawing State Methods ** ; ** ** ; **************************************************************************** ; ; * TQ3RendererStartFrame ; * ; * The StartFrame method is called first at Q3View_StartRendering ; * and should: ; * - initialize any renderer state to defaults ; * - extract any and all useful data from the drawContext ; * ; * If your renderer passed in kQ3RendererFlagClearBuffer at ; * registration, then it should also: ; * - clear the drawContext ; * ; * When clearing, your renderer may opt to: ; * - NOT clear anything (if you touch every pixel, for example) ; * - to clear with your own routine, or ; * - to use the draw context default clear method by calling ; * Q3DrawContext_Clear. Q3DrawContext_Clear takes advantage of ; * any available hardware in the system for clearing. ; * ; * This call also signals the start of all default submit commands from ; * the view. The renderer will receive updates for the default view ; * state via its Update methods before StartPass is called. ; * ; * REQUIRED ; kQ3XMethodTypeRendererStartFrame EQU 'rdcl' ; ; * kQ3XMethodTypeRendererStartPass ; * TQ3XRendererStartPassMethod ; * ; * The StartPass method is called during Q3View_StartRendering but after ; * the StartFrame command. It should: ; * - collect camera and light information ; * ; * If your renderer supports deferred camera transformation, camera is the ; * main camera which will be submitted in the hierarchy somewhere. It ; * is never NULL. ; * ; * If your renderer does not support deferred camera transformation, camera ; * is the transformed camera. ; * ; * If your renderer supports deferred light transformation, lights will be ; * NULL, and will be submitted to your light draw methods instead. ; * ; * This call signals the end of the default update state, and the start of ; * submit commands from the user to the view. ; * ; * REQUIRED ; kQ3XMethodTypeRendererStartPass EQU 'rdst' ; ; * kQ3XMethodTypeRendererFlushFrame ; * TQ3XRendererFlushFrameMethod ; * ; * This call is only implemented by asynchronous renderers. ; * ; * The FlushFrame method is called between the StartPass and EndPass ; * methods and is called when the user wishes to flush any asynchronous ; * drawing tasks (which draw to the drawcontext), but does not want ; * to block. ; * ; * The result of this call is that an image should "eventually" appear ; * asynchronously. ; * ; * For asynchronous rendering, this call is non-blocking. ; * ; * An interactive renderer should ensure that all received ; * geometries are drawn in the image. ; * ; * An interactive renderer that talks to hardware should force ; * the hardware to generate an image. ; * ; * A deferred renderer should exhibit a similar behaviour, ; * though it is not required. A deferred renderer should spawn ; * a process that generates a partial image from the currently ; * accumulated drawing state. ; * ; * However, for renderers such as ray-tracers which generally are ; * quite compute-intensive, FlushFrame is not required and is a no-op. ; * ; * OPTIONAL ; kQ3XMethodTypeRendererFlushFrame EQU 'rdfl' ; ; * kQ3XMethodTypeRendererEndPass ; * TQ3XRendererEndPassMethod ; * ; * The EndPass method is called at Q3View_EndRendering and signals ; * the end of submit commands to the view. ; * ; * If an error occurs, the renderer should call Q3XError_Post and ; * return kQ3ViewStatusError. ; * ; * If a renderer requires another pass on the renderering data, ; * it should return kQ3ViewStatusRetraverse. ; * ; * If rendering was cancelled, this function will not be called ; * and the view will handle returning kQ3ViewStatusCancelled; ; * ; * Otherwise, your renderer should begin completing the process of ; * generating the image in the drawcontext. If you have buffered ; * any drawing data, flush it. RendererEnd should have a similar ; * effect as RendererFlushFrame. ; * ; * If the renderer is synchronous: ; * - complete rendering of the entire frame ; * if the renderer supports kQ3RendererClassSupportDoubleBuffer ; * - Update the front buffer ; * else ; * - DrawContext will update the front buffer after returning ; * ; * If the renderer is asynchronous ; * - spawn rendering thread for entire frame ; * if the renderer supports kQ3RendererClassSupportDoubleBuffer, ; * - you must eventually update the front buffer asynchronously ; * else ; * - you must eventually update the back buffer asynchronously ; * ; * REQUIRED ; kQ3XMethodTypeRendererEndPass EQU 'rded' ; ; * kQ3XMethodTypeRendererEndFrame ; * TQ3XRendererEndFrame ; * ; * This call is only implemented by asynchronous renderers. ; * ; * The EndFrame method is called from Q3View_Sync, which is ; * called after Q3View_EndRendering and signals that the user ; * wishes to see the completed image and is willing to block. ; * ; * If your renderer supports kQ3RendererFlagDoubleBuffer ; * - update the front buffer completely ; * else ; * - update the back buffer completely ; * ; * This call is equivalent in functionality to RendererFlushFrame ; * but blocks until the image is completed. ; * ; * If no method is supplied, the default is a no-op. ; * ; * NOTE: Registering a method of this type indicates that your renderer will ; * be rendering after Q3View_EndRendering has been called. ; * ; * OPTIONAL ; kQ3XMethodTypeRendererEndFrame EQU 'rdsy' ; ; * The RendererCancel method is called after Q3View_StartRendering ; * and signals the termination of all rendering operations. ; * ; * A renderer should clean up any cached data, and cancel all ; * rendering operations. ; * ; * If called before Q3View_EndRendering, the RendererEnd method ; * is NOT called. ; * ; * If called after Q3View_EndRendering, the renderer should kill ; * any threads and terminate any further rendering. ; * ; * REQUIRED ; kQ3XMethodTypeRendererCancel EQU 'rdab' ; ****************************************************************************** ; ** ** ; ** Renderer DrawContext Methods ** ; ** ** ; **************************************************************************** ; ; * kQ3XMethodTypeRendererPush ; * TQ3XRendererPushMethod ; * ; * kQ3XMethodTypeRendererPop ; * TQ3XRendererPopMethod ; * ; * These methods are called whenever the graphics state in the view ; * is pushed or popped. The user may isolate state by calling: ; * ; * Q3Attribute_Submit(kQ3AttributeTypeDiffuseColor, &red, view); ; * Q3Attribute_Submit(kQ3AttributeTypeTransparencyColor, &blue, view); ; * Q3Attribute_Submit(kQ3AttributeTypeSpecularColor, &white, view); ; * Q3Box_Submit(&unitBox, view); ; * Q3TranslateTransform_Submit(&unitVector, view); ; * Q3Push_Submit(view); ; * Q3Attribute_Submit(kQ3AttributeTypeDiffuseColor, &blue, view); ; * Q3Attribute_Submit(kQ3AttributeTypeTransparencyColor, &green, view); ; * Q3Box_Submit(&unitBox, view); ; * Q3Pop_Submit(view); ; * Q3TranslateTransform_Submit(&unitVector, view); ; * Q3Box_Submit(&unitBox, view); ; * ; * or by submitting a display group which pushes and pops. ; * ; * If you support RendererPush and RendererPop in your renderer: ; * - you must maintain your drawing state as a stack, as well. ; * - you will not be updated with the popped state after ; * RendererPop is called. ; * ; * If you do not support Push and Pop in your renderer: ; * - you may maintain a single copy of the drawing state. ; * - you will be updated with changed fields after the view stack is ; * popped. ; * ; * A renderer that supports Push and Pop gets called in the following ; * sequence (from example above): ; * ; * RendererUpdateAttributeDiffuseColor(&red,...) ; * RendererUpdateAttributeTransparencyColor(&blue,...) ; * RendererUpdateAttributeSpecularColor(&white,...) ; * RendererUpdateMatrixLocalToWorld(...) ; * RendererSubmitGeometryBox(...) ; * RendererPush(...) ; * RendererUpdateAttributeDiffuseColor(&blue,...) ; * RendererUpdateAttributeTransparencyColor(&green,...) ; * RendererSubmitGeometryBox(...) ; * RendererPop(...) ; * RendererUpdateMatrixLocalToWorld(...) ; * RendererSubmitGeometryBox(...) ; * ; * A renderer that does not supports Push and Pop gets called in the ; * following sequence: ; * ; * RendererUpdateAttributeDiffuseColor(&red,...) ; * RendererUpdateAttributeTransparencyColor(&blue,...) ; * RendererUpdateAttributeSpecularColor(&white,...) ; * RendererUpdateMatrixLocalToWorld(...) ; * RendererSubmitGeometryBox(...) ; * RendererUpdateAttributeDiffuseColor(&blue,...) ; * RendererUpdateAttributeTransparencyColor(&green,...) ; * RendererSubmitGeometryBox(...) ; * RendererUpdateAttributeDiffuseColor(&red,...) ; * RendererUpdateAttributeTransparencyColor(&blue,...) ; * RendererUpdateMatrixLocalToWorld(...) ; * RendererSubmitGeometryBox(...) ; * ; kQ3XMethodTypeRendererPush EQU 'rdps' kQ3XMethodTypeRendererPop EQU 'rdpo' ; ****************************************************************************** ; ** ** ; ** Renderer Cull Methods ** ; ** ** ; **************************************************************************** ; ; * kQ3XMethodTypeRendererIsBoundingBoxVisible ; * TQ3XRendererIsBoundingBoxVisibleMethod ; * ; * This method is called to cull complex groups and geometries ; * given their bounding box in local space. ; * ; * It should transform the local-space bounding box coordinates to ; * frustum space and return a TQ3Boolean return value indicating ; * whether the box appears within the viewing frustum. ; * ; * If no method is supplied, the default behavior is to return ; * kQ3True. ; * ; kQ3XMethodTypeRendererIsBoundingBoxVisible EQU 'rdbx' ; ****************************************************************************** ; ** ** ; ** Renderer Object Support Methods ** ; ** ** ; **************************************************************************** ; ; * Drawing methods (Geometry, Camera, Lights) ; * ; ; ; * Geometry MetaHandler ; * ; * This metaHandler is required to support ; * ; * kQ3GeometryTypeTriangle ; * kQ3GeometryTypeLine ; * kQ3GeometryTypePoint ; * kQ3GeometryTypeMarker ; * kQ3GeometryTypePixmapMarker ; * ; * REQUIRED ; kQ3XMethodTypeRendererSubmitGeometryMetaHandler EQU 'rdgm' ; ; * The TQ3XRendererSubmitGeometryMetaHandlerMethod switches on geometryType ; * of kQ3GeometryTypeFoo and returns methods of type: ; ; ; * Camera MetaHandler ; * ; * This metaHandler, if supplied, indicates that your renderer ; * handles deferred transformation of the main camera within a scene. ; * ; * If not supplied, or an unsupported camera is used, the view will do ; * the transformation for the renderer and pass in a camera in the ; * StartPass method. ; * ; * OPTIONAL ; kQ3XMethodTypeRendererSubmitCameraMetaHandler EQU 'rdcm' ; ; * The TQ3XRendererSubmitCameraMetaHandlerMethod switches on cameraType ; * of kQ3CameraTypeFoo and returns methods of type: ; ; ; * Light MetaHandler ; * ; * This metaHandler, if supplied, indicates that your renderer ; * handles deferred transformation of lights within a scene. ; * ; * If an unsupported light is encountered, it is ignored. ; * ; * OPTIONAL ; kQ3XMethodTypeRendererSubmitLightMetaHandler EQU 'rdlg' ; ; * The TQ3XRendererSubmitLightMetaHandlerMethod switches on lightType ; * of kQ3LightTypeFoo and returns methods of type: ; ; ; * ; * Update methods ; * ; * They are called whenever the state has changed. If the renderer supports ; * the RendererPush and RendererPop methods, it must maintain its own state ; * stack. Updates are not called for changed data when the view stack is ; * popped. ; * ; * See the comments for the RendererPush and RendererPop methods above ; * for an example of how data is updated. ; * ; ; ; * Style ; kQ3XMethodTypeRendererUpdateStyleMetaHandler EQU 'rdyu' ; ; * The TQ3XRendererUpdateStyleMetaHandlerMethod switches on styleType ; * of kQ3StyleTypeFoo and returns methods of type: ; ; ; * Attributes ; kQ3XMethodTypeRendererUpdateAttributeMetaHandler EQU 'rdau' ; ; * The TQ3XRendererUpdateStyleMetaHandlerMethod switches on attributeType ; * of kQ3AttributeTypeFoo and returns methods of type: ; ; ; * Shaders ; kQ3XMethodTypeRendererUpdateShaderMetaHandler EQU 'rdsu' ; ; * The TQ3XRendererUpdateShaderMetaHandlerMethod switches on shaderType ; * of kQ3ShaderTypeFoo and returns methods of type: ; ; ; * Matrices ; kQ3XMethodTypeRendererUpdateMatrixMetaHandler EQU 'rdxu' ; typedef TQ3XMetaHandler TQ3XRendererUpdateMatrixMetaHandlerMethod ; ; * The TQ3XRendererUpdateShaderMetaHandlerMethod switches on methods ; * of the form kQ3MethodTypeRendererUpdateMatrixFoo: ; kQ3XMethodTypeRendererUpdateMatrixLocalToWorld EQU 'ulwx' kQ3XMethodTypeRendererUpdateMatrixLocalToWorldInverse EQU 'ulwi' kQ3XMethodTypeRendererUpdateMatrixLocalToWorldInverseTranspose EQU 'ulwt' kQ3XMethodTypeRendererUpdateMatrixLocalToCamera EQU 'ulcx' kQ3XMethodTypeRendererUpdateMatrixLocalToFrustum EQU 'ulfx' kQ3XMethodTypeRendererUpdateMatrixWorldToFrustum EQU 'uwfx' ; ; * and returns methods of type: ; ENDIF ; __QD3DRENDERER__